home *** CD-ROM | disk | FTP | other *** search
/ Atari Forever 3 / Atari Forever 3 / Atari Forever 3.iso / PD_NEU / INTERNET / CAB / DOC / PROGRAMI / MODUL_E.DOC < prev    next >
Encoding:
Text File  |  1996-08-31  |  16.0 KB  |  406 lines
  1. Overview of the CAB (formerly HTML-Browser) interface module
  2. ============================================================================
  3.  
  4. Contact
  5. -------
  6. Alexander Clauss
  7. Stresemannstr. 44
  8. D-64297 Darmstadt
  9. Germany
  10.  
  11. Email: aclauss@rbg.informatik.th-darmstadt.de
  12.  
  13. Important!
  14. ----------
  15. CAB does not possess any online routines to connect to the internet (i.e
  16. the WWW). In fact I don't even own a modem so cannot test these routines.
  17. I have provided an interface which programmers can use to add their own
  18. routines and these are intergrated with CAB via the CAB.OVL file.
  19.  
  20. The interface works under single TOS and doesn't use any special Mint
  21. features. If this isn't suitable for your needs please get in touch to
  22. discuss your requirements...
  23.  
  24. The interface is still under development and there's still plenty of room
  25. for improvement. There were even a few superfluous calls in the alpha
  26. version of the module which are unlikely to be needed (e.g begin_pexec(),
  27. end_pexec() were included because early data transfer trials used ZModem!
  28.  
  29. All suggestions for improving the module are gratefully received.
  30.  
  31.  
  32. Calling the module
  33. ------------------
  34. CAB calls the functions of CAB.OVL in the same way as the normal
  35. subroutines of CAB.APP. But to do so CAB needs to know where these
  36. functions are (i.e. the addresses in memory). One way to find the
  37. addresses is as follows:
  38. CAB.OVL includes a unique sequence of characters (or numbers) -the so
  39. called 'magic number' -immediately followed by the address of the
  40. 'OVL_init' function (which is easy to arrange when writing the CAB.OVL).
  41. CAB searches for the magic number and if it's found CAB.APP can now locate
  42. the address of the init function and call CAB.OVL.
  43.  
  44. Normally, the operating system (TOS) allocates all available memory to a
  45. program which is launched. The program knows how much memory it needs and
  46. must free the memory which it doesn't need as soon as possible (using the
  47. mshrink() system call). Ideally CAB.APP should perform the mshrink() call
  48. because CAB.OVL is not started as a normal program and should not
  49. (normally) call mshrink() directly.
  50. It would be possible for an OVL file to call mshrink() directly but only
  51. if the module is programmed in assembler so the options are:
  52.  
  53. 1) CAB.APP loads the module (CAB.OVL) using pexec(3,...). The module is
  54.    loaded into memory but not started. CAB.APP now searches for the 'magic
  55.    number' in the memory area of the module. Immediately following this
  56.    number the address of the initialisation routine of the module should
  57.    be placed. Now CAB.APP jumps to this function and passes two structures.
  58.    One of these structures contains functions which CAB.APP can provide
  59.    and the module can use. The other structure must be filled with the
  60.    initialisation function including the address of the module functions
  61.    so CAB.APP can call them.
  62.  
  63.    The 'magic number' is:
  64.    0x48744d6c, 0x2f577757, 0x2d42724f, 0x77536552
  65.    CAP.APP loads the module using mshrink() and frees up any remaining
  66.    unused memory.
  67.  
  68.    The module implements the mshrink() call itself, then passes the
  69.    following 'magic number':
  70.    0x48744d6c, 0x2f577757, 0x2d42724f, 0x77536572
  71.  
  72.  
  73.    Disdvantage:
  74.    The module startup code will not be executed with the consequence that
  75.    any function calls initialised in the startup code is not possible. For
  76.    example printf().
  77.  
  78. 2) Alternatively a program which includes the functions of the Internet
  79.    module can start CAB.APP. In this case CAB.APP must be called with the
  80.    command line: '-initfunc=<address>' where <address> is the address for
  81.    the init-function in decimal (NOT hexadecimal!). The 'magic number'
  82.    isn't needed in this case.
  83.  
  84. Under Mint with memory protection the 'Global' memory flag must be set
  85. (for both programs) so both programs can exchange calls with each other.
  86.  
  87. Function call conventions
  88. --------------------------
  89. All function parameters must be passed to the stack. The result is passed
  90. to register D0. 'long' variables are 32 bit wide and 'int' variables are
  91. 16 bit. Bit 0 denotes the lowest value bit.
  92.  
  93. For Pure C, this means: Additionally declare all functions with 'cdecl'
  94. For gcc this means: Use the '-mshort' option!
  95.  
  96.  
  97. Description of the module functions
  98. -----------------------------------
  99. In 'modul.h' and 'init.c' (compiled by Stephane Boisson) you'll find a
  100. basic schematic of a module.
  101. For call method 1) you must insert some dummy calls (which are never
  102. called) in main() so the compiler doesn't path optimise all the
  103. functions.
  104.  
  105. long init_module(url_methods_t *out, browser_info_t *in, char *path);
  106. ---------------------------------------------------------------------
  107. These functions call CAB.APP immediately after starting. These functions
  108. must intialise the module.
  109.  
  110.    'path'   Contains the path to the module including trailing '\'.
  111.             If a configuation has to be loaded it can be searched
  112.             for in this path.
  113.    'in'     All functions offered by CAB.APP.
  114.    'out'    In this structure the addresses of the module functions must
  115.             be entered. Any functions not implemented should be set to 0L.
  116.  
  117. The function (init_module) must return a 'long' value. Each bit of this
  118. value represents a protocol (ftp, news, http, etc.).
  119.  
  120. Constants for the protocols:
  121. SUPPORT_HTTP, SUPPORT_FTP, SUPPORT_GOPHER, SUPPORT_WAIS, SUPPORT_MAILTO,
  122. SUPPORT_NNTP, SUPPORT_TELNET
  123.  
  124. If the module starts further programs using pexec(0) you must add the
  125. following bit:
  126. SUPPORT_PEXEC
  127.  
  128. If the initialisation fails 0L must be returned; subsequent calls from
  129. module functions will not be found.
  130.  
  131. Important note for call method 1 (see start of text):
  132. The address of this function must lie immediately after the 'MagiC number'
  133. somewhere in the program or data area so that CAB.APP can find this
  134. function and call (only valid if the module was loaded from CAB.APP using
  135. pexec(3)).
  136.  
  137. Important note for call method 2 (see start of text):
  138. The module is started as a program which then starts CAB.APP itself
  139. passing the address of this function as a parameter:
  140.  
  141.   Parameter:  -initfunc=<address>
  142.  
  143.  
  144. void restore_module(void);
  145. --------------------------
  146. This function is called before CAB.APP exits. The function should release
  147. all requested memory, close open files etc.
  148.  
  149. Implement this function if the module reserves file handles, memory etc.
  150. It's called on exiting the program.
  151.  
  152. void get_version(char **authorp, long *versionp, long *datep);
  153. --------------------------------------------------------------
  154. These functions are all optional. Information about the author, version
  155. and date of the module. All entries are displayed in the CAB 'About...'
  156. dialog:
  157.  
  158.    'authorp'   Author and address. 4*30 characters max separated using '|'.
  159.    'versionp'  Version in BCD format. The upper word is the main version
  160.                number
  161.    'datep'     Date in BCD format: 0xYYYYMMDD (year,month,day)
  162.  
  163.  
  164. long get_url_info(char *url, long *timep, long *sizep, char *type);
  165. -------------------------------------------------------------------
  166. Obtain information about the file with the URL address 'url'. This
  167. information is used to determine if files available in the cache have
  168. changed before requesting them again from the Internet. Consequently it's
  169. important to set get_url() time and date (last modification) of the
  170. original file correctly.
  171.  
  172.    'url'    URL address of the document
  173.    'timep'  Date and time (last modification) in UNIX Format: Seconds
  174.             since 1970 (01.01.1970, 00:00 means *timep=0)
  175.    'sizep'  Length of the file, -1 if unknown.
  176.    'type'   File format in MIME format (e.g.: images/jpeg).
  177.             Size of the 'type' buffer: 200 characters.
  178.  
  179. The function returns 0 if everything went smoothly, otherwise a GEMDOS,
  180. XBIOS, BIOS, Mint i.e. MintNet error number is returned. Although this
  181. function is optional it is desirable for optimal cache management.
  182.  
  183.  
  184. long get_url(char *url, char *filename);
  185. ----------------------------------------
  186. Fetch data from the Internet (URL address: 'url') and write to the file
  187. 'filename'
  188.  
  189. 'filename' already contains the complete access path so directories do
  190. not need to be set.
  191. The file should be set to the last modified date of the document so that
  192. the cache can be managed in connection with 'get_url_info(..)'
  193.  
  194. If the destination URL address is a directory (e.g. for ftp, gopher
  195. protocol) then the resulting file should be saved as an HTML file (just in
  196. case the file isn't already in HTML format).
  197. If saving a directory contents as an HTML file the following 'inline
  198. images' can be used and assigned with a suitable icon as follows:
  199.  
  200.    #define BULLET_FOLDER "<img src=\"internal-gopher-menu\">"
  201.    #define BULLET_TEXT "<img src=\"internal-gopher-text\">"
  202.    #define BULLET_IMAGE "<img src=\"internal-gopher-image\">"
  203.    #define BULLET_MOVIE "<img src=\"internal-gopher-movie\">"
  204.    #define BULLET_SOUND "<img src=\"internal-gopher-sound\">"
  205.    #define BULLET_INDEX "<img src=\"internal-gopher-index\">"
  206.    #define BULLET_BINARY "<img src=\"internal-gopher-binary\">"
  207.    #define BULLET_UNKNOW "<img src=\"internal-gopher-unknown\">"
  208.  
  209. The function returns 0 if everything went smoothly, otherwise a GEMDOS,
  210. XBIOS, BIOS, Mint i.e. MintNet error number is returned.
  211.  
  212. If the URL address is diverted (Image-Maps,...) then CAB.APP must be
  213. informed using the 'new_url' function (refer to end of this document).
  214.  
  215.  
  216. long post(char *url,char *content, char *enctype, char *filename);
  217. ------------------------------------------------------------------
  218. The data ('content') of a FORM area should be sent using 'POST' to 'url'.
  219. The 'content' data is coded in the format specified in 'enctype'.
  220. Currently only the MIME format 'application/x-www-form-urlencoded' is
  221. possible/allowed. Eventually returned data may be saved in 'filename'.
  222. If the returned files possess a new URL address the 'new_url' function
  223. must be used (refer to end of this document).
  224.  
  225.  
  226. long mailto(char *url, char *subject, char *filename);
  227. ------------------------------------------------------
  228. The file 'filename' should be send as email with the subject 'subject'
  229. to the address with the URL 'url'.
  230. The function returns 0 if everything went smoothly, otherwise -1.
  231.  
  232.  
  233.  
  234.  
  235. Available CAB.APP functions (browser_info_t structure)
  236. ------------------------------------------------------
  237. The module can make direct AES calls but in general this should not be
  238. necessary.
  239.  
  240. void (*aes_crystal)(void)
  241. -------------------------
  242. If your module makes AES calls you should use the following arrays
  243. followed by the aes_crystal() call.
  244.  
  245.   int *aes_control;
  246.   int *aes_global;
  247.   int *aes_intin;
  248.   int *aes_intout;
  249.   long *aes_addrin;
  250.   long *aes_addrout;
  251.  
  252.  
  253. void (*aes_messages)(int *msg)
  254. ------------------------------
  255. If your module handles its own AES events they should pass such events to
  256. CAB.APP using this function.
  257.  
  258.  
  259. void (*msg_error)(long errno)
  260. -----------------------------
  261. Outputs an error message to the status window of HTML.APP. All the GEMDOS,
  262. BIOS and MintNet error numbers are allowed.
  263.  
  264.  
  265. void (*msg_status)(long no,long val)
  266. ------------------------------------
  267. Outputs one of the following status messages:
  268.  
  269.    no=1: 'connecting host',      val unused
  270.    no=2: 'receive data',         val=number of bytes received
  271.    no=3: 'waiting for response', val unused
  272.    no=4: 'resolving host',       val unused
  273.    no=5: 'sending request',      val unused
  274.    no=6: 'format text...',       val unused
  275.    no=7: 'Load image...',        val unused
  276.    no=8: 'start program...',     val unused
  277.  
  278. Other status messages could be added if required, please discuss your
  279. requirements with me...
  280.  
  281.  
  282. long (*aes_events)(long msec)
  283. -----------------------------
  284. CAB.APP makes an evnt_multi() call to set MU_MESAG, MU_TIMER and MU_KEYBD.
  285. 'msec' is set as the value for the timer-event. Setting a low value for
  286. 'msec' means the function is turned around faster. CAB.APP currently
  287. processes all separate events (e.g. redraw, move window..) and checks
  288. whether the user wishes to cancel the action. This function returns the
  289. following results:
  290.  
  291.     0        -> no MU_MESAG event
  292.    -1        -> abort action (e.g. Internet connection)
  293.    all other -> pointer to GEM message array
  294.  
  295.  
  296. long (*alert_box)(long button,long msg)
  297. ---------------------------------------
  298. An alert box will be displayed. 'button' is the default button and 'msg'
  299. is the number of the text. The function returns 0 if an error is
  300. encountered (false msg number) otherwise the selected button.
  301. Possible text (msg):
  302.  
  303.    msg=0 : "[2][Cancel action?][Yes|No]"
  304.  
  305. Other messages could be added if required, please discuss your
  306. requirements with me...
  307.  
  308.  
  309. void (*begin_pexec)(void)    void (*end_pexec)(void)
  310. ----------------------------------------------------
  311. If you intend to start another program from inside the module using
  312. pexec(0,..) then a begin_pexec() call must be made before calling pexec().
  313. Afterwards an end_pexec() call must also be made. Under single TOS you
  314. must de-initialise the AES before starting another program. After exiting
  315. this program you must re-initialise the AES. CAB.APP performs the
  316. de/initialisations but it must know when the program is started.
  317.  
  318.  
  319. int (*clear_cache)(long size)
  320. -----------------------------
  321. If no free disk space is available to save incoming data this function can
  322. be called. CAB.APP then checks the minimum 'size' in bytes set for the
  323. cache and partly deletes the contents to free up disk space. The function
  324. returns 0 if successful otherwise -1.
  325.  
  326. Size=0 means the entire cache is deleted.
  327.  
  328.  
  329. int (*new_url)(char *url,char **file)
  330. -------------------------------------
  331. If a document request is diverted to a new URL address (e.g. Imagemaps,
  332. cgi-Scripts) this function must be used to inform the main program. It
  333. then ascertains a new filename 'file' under which to save the data.
  334. If the function returns the result 0 the document is fetched. If the
  335. result is -1 then it's not necessary to fetch the file as it already
  336. exists in the cache.
  337.  
  338.  
  339. int (*ask_user)(long msg,char **answer)
  340. ---------------------------------------
  341. If the user has to enter data, before continuing (for example with
  342. password protected documents) this function can be used. 'msg' is the
  343. number of the texts to be displayed 'answer' is the string entered by the
  344. user.
  345. The returned values may be: 1 if the user pressed OK, 0 if the user
  346. pressed Cancel or -1 on error/s (wrong msg no.)
  347.  
  348. The 'answer' string will be overwritten by the next call of this function
  349. so you should copy the string if necessary.
  350.  
  351. Possible values for 'msg' are:
  352.  
  353.     msg=0 Document protected, name (e.g I.D) enter
  354.     msg=1 Document protected, enter password
  355.  
  356. Other messages could be added if required, please discuss your
  357. requirements with me...
  358.  
  359.  
  360. long basepage
  361. -------------
  362. Address of the basepage.
  363. Only valid if the module was started with pexec(3).
  364.  
  365.  
  366. int *reloadflag
  367. ---------------
  368. *reloadflag is 1 if the user wants to reload the page, 0 otherwise.
  369.  
  370.  
  371. long version
  372. ------------
  373. Version number of CAB in ASCII format. Example: V1.30 is 0x30313330.
  374.  
  375.  
  376. proxy_url *proxy
  377. ----------------
  378. Pointer to the following struct:
  379.  
  380. struct {
  381.    char *ftp_proxy;
  382.    char *http_proxy;
  383.    char *wais_proxy;
  384.    char *gopher_proxy;
  385.    char *news_proxy;
  386.    char *no_proxy;
  387.    char *smtp_server;
  388.    char *nntp_server;
  389. } proxy_url
  390.  
  391. The OVL should fill out this struct in the init function with
  392. default values. CAB has already allocated the memory for all the
  393. strings (126 Bytes each). CAB itself will change these entries
  394. with the values the user entered in CAB. The OVL should look at
  395. these entries before getting the files, so it uses the right values.
  396.  
  397.  
  398. void online(int state)
  399. ----------------------
  400. The OVL should call this function whenever the internet connection
  401. is enabled or disabled. If the OVL is connected to the internet
  402. (online) set state=1, if there's no internet connection (offline)
  403. set state=0. This function is available since CAB version 1.41
  404. (that means version>=0x30313431). If the OVL doesn't call this
  405. function CAB thinks it is online.
  406.